{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Machine Learning on PYNQ\n",
    "\n",
    "\n",
    "## Introduction\n",
    "\n",
    "Artificial intelligence, deep learning, and neural networks represent incredibly exciting and powerful machine learning-based techniques used to solve many real-world problems. Neural networks, which a inspired by the human brain, are now the predominant vision processing algorithms, exceeding humans in accuracy in multiple applications. They are capable of modelling and processing nonlinear relationships between inputs and outputs in parallel and they are characterized by containing adaptive weights along paths between neurons which are tuned during training time. Once the parameters are learned, they can be used in the field to perform inference.\n",
    "\n",
    "\n",
    "## Quantization of neural networks\n",
    "\n",
    "Weights, or network parameters, in neural networks are traditionally represented with 32bit float data types. Recent research shows that weights with 8, 4, 2, or 1bit fixed point values are sufficient. However, compared to 32 bit float which represents values between 10^-38 to 10^+38, the dynamic range has been hugely reduced with quantization.\n",
    "\n",
    "Intuitively you might think this would highly reduce the accuracy of the neural network, but it was demonstrated for numerous popular networks, that if the training is performed already with these quantized weights, they can maintain a very reasonable level of accuracy.\n",
    "\n",
    "The advantages are significant because:\n",
    "\n",
    "* reduced precision fixed point values are smaller, so storing millions of weights represents significant memory savings\n",
    "\n",
    "* reduced precision arithmetic is cheaper (area and power) than floating point, and programmable logic, thanks to its flexibility, is a perfect match to implement such ad-hoc reduced precision arithmetic cores\n",
    "\n",
    "\n",
    "## Available overlays\n",
    "\n",
    "The examples that are currently available can be split in 2 categories:\n",
    "\n",
    "* **bnn**: stands for Binarized Neural Network. The quantization process goes down to a single bit for all the parameters. In this specific case, the MAC arithmetic can be simplified to XNOR and popcount operations.\n",
    "\n",
    "* **qnn**: stands for Quantized Neural Network. In this case, parameters can have flexible bit widths\n",
    "\n",
    "The current release shows 2 examples per each category. Another distinctive difference among the available overlays is the actual hardware architecture:\n",
    "\n",
    "* **Feed-forward Dataflow**: all layers of the network are implemented in the hardware, the output of one layer is the input of the following one that starts processing as soon as data is available. The network parameters for all layers are cached in the on-chip memory. For each network topology, a customized hardware implementation is generated that provides low latency and high throughput.\n",
    "\n",
    "* **Multi-layer offload**: a fixed hardware architecture is implemented, being able to compute multiple layers in a single call. The complete network is executed in multiple calls, which are scheduled on the same hardware architecture. Changing the network topology implies changing the runtime scheduling, but not the hardware architecture. This provides a flexible implementation but features slightly higher latency.\n",
    "\n",
    "In the current release, the 2 **bnn** overlays are implemented in feed-forward dataflow architecture with fixed topologies, while the 2 **qnn** overlays feature a multi-layer offload architecture with support to 2-bits and 3-bits for the activations.\n",
    "\n",
    "## Available examples\n",
    "\n",
    "Multiple notebooks examples are provided, with different dataset and several architecture.\n",
    "\n",
    "The BNN based notebooks with dataflow are:\n",
    "\n",
    "* [Cifar10](/notebooks/bnn/Cifar10.ipynb): shows a convolutional neural network, composed of 6 convolutional, 3 max pool and 3 fully connected layers trained on the <a href=\"https://www.cs.toronto.edu/~kriz/cifar.html\" target=\"_blank\"> Cifar10 </a> dataset\n",
    "\n",
    "* [SVHN](/notebooks/bnn/SVHN.ipynb): shows a convolutional neural network, composed of 6 convolutional, 3 max pool and 3 fully connected layers trained on the <a href=\"http://ufldl.stanford.edu/housenumbers/\" target=\"_blank\"> Street View House Number </a> dataset\n",
    "\n",
    "* [GTRSB](/notebooks/bnn/Road-Signs-Batch.ipynb): shows a convolutional neural network, composed of 6 convolutional, 3 max pool and 3 fully connected layers trained on the <a href=\"http://benchmark.ini.rub.de/?section=gtsdb&subsection=dataset\" target=\"_blank\"> German Road Sign </a> dataset\n",
    "\n",
    "* [MNIST](/notebooks/bnn/BNN-from-webcam.ipynb): shows a multi layer perceptron with 3 fully connected layers trained on the <a href=\"http://yann.lecun.com/exdb/mnist/\" target=\"_blank\"> MNIST </a> dataset for digit recognition\n",
    "\n",
    "The QNN based notebooks with multi-layer offload are:\n",
    "\n",
    "* [ImageNet Classification](/notebooks/qnn/dorefanet-classification.ipynb): shows an example on how to classify a non-labelled image (e.g., downloaded from the web, your phone etc) in one of the 1000 classes available on the <a href=\"http://image-net.org/challenges/LSVRC/2014/browse-synsets\" target=\"_blank\"> ImageNet </a> dataset.  \n",
    "\n",
    "* [ImageNet - Dataset validation](/notebooks/qnn/dorefanet-imagenet-samples.ipynb): shows an example classifying labelled image (i.e.,  extracted from the dataset) in one of the 1000 classes available on the <a href=\"http://image-net.org/challenges/LSVRC/2014/browse-synsets\" target=\"_blank\"> ImageNet </a> dataset.  \n",
    "\n",
    "* [ImageNet - Dataset validation in a loop](/notebooks/qnn/dorefanet-imagenet-loop.ipynb): shows an example classifying labelled image (i.e.,  extracted from the dataset) in one of the 1000 classes available on the <a href=\"http://image-net.org/challenges/LSVRC/2014/browse-synsets\" target=\"_blank\"> ImageNet </a> dataset in a loop.\n",
    "\n",
    "* [Object Detection - from image](/notebooks/qnn/tiny-yolo-image.ipynb): shows object detection in a image (e.g., downloaded from the web, your phone etc), being able to identify objects in a scene and drawing bounding boxes around them. The objects can be one of the 20 available in the  <a href=\"http://host.robots.ox.ac.uk/pascal/VOC/\" target=\"_blank\"> PASCAL VOC </a> dataset\n",
    "\n",
    "* [Object Detection - from image in a loop](/notebooks/qnn/tiny-yolo-image-loop.ipynb): shows object detection in a image and draws bounding boxes around indentified objects (20 available classes from <a href=\"http://host.robots.ox.ac.uk/pascal/VOC/\" target=\"_blank\"> PASCAL VOC </a> dataset) in a loop.\n",
    "\n",
    "\n",
    "## GitHub\n",
    "\n",
    "The Pynq BNN-PYNQ Repository is hosted on github: <a href=\"https://github.com/Xilinx/BNN-PYNQ\"> BNN-PYNQ GitHub Repository</a>.\n",
    "\n",
    "The Pynq QNN-MO-PYNQ Repository is hosted on github: <a href=\"https://github.com/Xilinx/QNN-MO-PYNQ\"> QNN-MO-PYNQ GitHub Repository</a>."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
